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Abstract 



We describe a C package for arbitrary-precision integer arithmetic that is portable, yet efficient. 
Making the package run fast on a given computer involves re-writing a small kernel of our 
package in native assembly language. We provide such assembly code for VAX, 68020 and 
NS instruction sets, with good benchmarks. This package serves as a foundation for two 
arithmetic packages written in higher level languages LeLisp 1 and Modula2+. 

This package is available to non-commercial users. 



Resume 



Nous decrivons un module C d'arithmetique entiere a precision arbitraire, portable, mais 
neanmoins efficace. La rapidite d'execution de ce module est assujettie a la reecriture en 
langage machine du noyau du module. Nous fournissons les codes assembleurs pour les 
machines VAX, Mips, 68020 et NS. Ce module sert comme base pour deux bibliotheques 
arithmetiques ecrites en langages de haut niveau LeLisp 2 et Modula2+. 

Ce module est du domaine public pour toute utilisation non commerciale. 



1 LeLisp is a registered trademark of INRIA. 
2 LeLisp est une marque deposee par 1'INRIA 
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1 Introduction 

Developing an arbitrary-precision arithmetic package that is both efficient and portable 
brings up two main problems: 

• If an arithmetic package is written in a high-level language (such as languages Modula2+, 
LeLisp , C,. . . ), the compiled code will typically be 4 to 10 times slower than carefully 
hand-crafted machine code. 

• Many important arithmetic computations run an order of magnitude faster when all 
forms of storage allocation are removed from the inner loop, storing intermediate and 
final results exclusively in the memory area used by input variables. Yet some advanced 
form of automatic storage management and garbage collection must be part of any 
useful arithmetic package; furthermore, the number allocator must blend well with 
native storage allocation in the host language. 

To satisfy these conflicting requirements, we have organized our software in two layers: 

1. A layer called Bn, in which every operation deals with unsigned integers, allocates no 
storage, and returns results in place of the first argument passed to the routine. 

2. A layer called Bz, implemented on top of Bn, which implements signed arithmetic 
operations and allocates storage for the results, in a straightforward manner. 

Any high-level language C capable of interfacing directly with the language C can do so 
directly with Bn and Bz. When language C possesses its own storage allocator (possibly with 
garbage collection, as in LeLisp and Modula2+), it is best to rewrite directly in C the (small) 
storage allocation code of the Bz package. In this way, allocating and freeing numbers is 
directly handled in C. 

For speed reasons, the package Bn itself is structured in two layers: 

• The kernel KerN, which contains code for the time-critical low-level operations. 

• The rest of Bn, whose C code calls the kernel. 

The kernel KerN is written in C for portability and documentation, and can be compiled as 
such. However, to obtain a truly efficient implementation on a given machine, KerN must be 
directly written in assembly code, which we provide for VAX, 68020, and NS instruction sets. 
KerN is small indeed: 325 to 475 lines of C code, and 500 to 700 lines of VAX assembly code. 

The non-kernel part of Bn is written in C and compiled directly. The distinction between 
kernel and non-kernel operations is defined so that the time penalty for running the mixture 
of assembly and C code, as opposed to pure assembly code, is less than 20% on typical 
benchmarks. The knowledge of which procedures are in KerN is only important for someone 
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who attempts to port the package on a new machine and who is not satisfied with the speed of 
the C implementation. 

Finally, we point out that Bn has proved to be a sound basis on which to develop other 
specialized packages, such as rational, polynomial or modular arithmetic. Having full control 
over the exact storage representation of numbers is the key to truly fast implementations of 
such extensions to the basic package. 

Details on how to obtain this package are in appendix B. 
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2 Number representation 



Using radix b positional notation, an integer N e N can be written as: 



N= ^2 riih 1 = b [n 0 ■ ■ -n n ;-i]- 

0<i<nl 



In this equation: 

• b > 1 is the base. 

• For alH, 0 < i < nl, n{ are the digits of N written in base b, such that n; e B& = 



• The length nl of N is any integer greater than or equal to the number \logb(N + 1)] of 
significant digits of N written in base b. 

In the implementation, the base b is the largest power of two (typically 16 or 32) such that 
a digit fits in a memory word, and the instruction set supports base b unsigned extended 
arithmetic. The digit bit length is parameterized in the global C constant 



In Bn, an integer N e N is passed as a pair ( n , nl ) where: 

1. n is a pointer inside an array of consecutive digits, 

2. nl is the number (length) of digits from n in base b. 

Thus, for 0 < i < nl, n; is the content of memory location n + i. We use below the notation: 



for the integer N. 

In Bz, an integer is passed as a pointer to an array of consecutive digits; the header of this 
array contains the size (number of digits) of the array, and the sign of the number, defined as: 



[0..b- 1]. 



BN_DIGIT_SIZE = log 2 (b). 



N= ^2 ntf = (n,nl) = b [n 0 ■ ■ ■ n n ;-i]- 



0<i<nl 



sgn(z) = < 



1 if z < 0 

0 if z = 0 

1 if z > 0 
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The implementation defines the following C types: 



typedef unsigned int BigNumDigit ; /* A single 32 bits digit * 

typedef BigNumDigit BigNumCarry ; /* Either 0 or 1 */ 

typedef BigNumDigit * BigNum; /* Entity seen by the user 

typedef int BigNumCmp; /* = -1, 0, or 1 */ 

typedef int Boolean; 



Note that for the 16 bit implementation, the type BigNumDigit must be cast to a C 

unsigned short. 
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3 In place operations: Bn 

We classify the procedures in Bn according to their underlying mathematical operations. 

3.1 Initialization 

Procedure 1 Initialization Bnnlnit: 

• C header: 

void Bnnlnit ( ) 

• Inputs: none 

• Output: none 

• Side Effect: initializes Bn. 

Note: Bnnlnit £ KerN. 

Procedure 2 Closing BnnClose: 

• C header: 

void BnnClose () 

• Inputs: none 

• Output: none 

• Side Effect: closes Bn. 

Note: BnnClose <t KerN. 

3.2 Addition 

Procedure 3 Increment BnnAddCarry: 

• C header: 
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BigNumCarry BnnAddCarry (n, nl, c) 
BigNum n; 
unsigned nl; 
BigNumCarry c; 

• Inputs: 

1. N = (n,nl) = (.[no •• -Knl-i], the integer to be incremented. 

2. c g B2, the carry in. 

• Invariant: N+c = S = b [s 0 ■ ■ ■ s n i_is n i\. 

• Output: the carry out s n i e B2. 

• Side Effect: the nl least significant digits of S are stored back in memory locations n 
through n + nl — I as a side effect on the first argument n of the procedure: 

b [sQ ■ --Sni-i] =^ (n, nl) . 

Note: BnnAddCarry e KerN; the output is 1 iff N = b nl — 1 and c = 1; nl can be equal 
to zero, in which case the carry out has the same value as the carry in. 

Procedure 4 Addition BnnAdd: 

• C header: 

BigNumCarry BnnAdd (m, ml, n, nl, c) 
BigNum m, n; 
unsigned ml, nl; 
BigNumCarry c; 

• Inputs: 

1. M = (m,ml) = & [mo • • • m m /_i], the addend; 

2. N = (n,nl) = f,[no • • • n n i-\], the augend, no longer than the addend: 
nl < ml. 

3. c g B2, the carry in. 

• Invariant: N + M + c = S = b[so • • • s m i-is m il 

• Output: the carry out s m i e B2. 

• Side Effect: b[so • • -Smi-i] =>■ (m, ml). 

Note: BnnAdd G KerN; it is possible to call BnnAdd with m = n; nl can be equal to 
zero, in which case the operation BnnAdd is equivalent to BnnAddCarry (m, ml, c) . 
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3.3 Subtraction 

Procedure 5 Additive Inverse BnnComplement: 

• C header: 

void BnnComplement (n, nl) 
BigNum n; 
unsigned nl; 

• Input N = (n,nl) = b [n 0 ■ ■ • n n ;-i]- 

• Invariant: N + N = b nl - 1 ; N = (,[no • • • n n ;-iL with n~k = b - nk - 1 . 

• Output: none 

• Side Effect: (,[no • • -n^TT] => (n,nl). 

Note: BnnComplement e KerN; does nothing when nl = 0. 
Procedure 6 Decrement BnnSubtractBorrow: 

• C header: 

BigNumCarry BnnSubtractBorrow (n, nl, br) 
BigNum n; 
unsigned nl; 
BigNumCarry br; 

• Inputs: 

1. N = (n,nl) = (,[na •• -Knl-i], the integer to be decremented. 

2. br g B2, the borrow in. 

• Invariant: N + b nl + br - 1 = S = b[so ■ ■ ■ s ni-is n i]- 

• Output: the borrow out s n i e B2. 

• Side Effect: b[so ■ ■ ■ s ni-i] => (n,nl). 

Note: BnnSubtractBorrow g KerN; the output is 0 iff N = br = 0; nl can be equal 
to zero, in which case the carry out has the same value as the carry in. 

Procedure 7 Subtraction BnnSubtract: 

• C header: 
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BigNumCarry BnnSubtract (m, ml, n, nl, br) 
BigNum m, n; 
unsigned ml, nl; 
BigNumCarry br; 

• Inputs: 

1. M = (m, ml) = },[mQ- ■ -rumi-i], the positive term; 

2. N = (n,nl) = f,[no •• -Knl-i], the negative term, no longer than the positive: 
nl < ml. 

3. br e B2, the borrow in. 

• Invariant: M + b m ' - N + br - 1 = S = b[so • • • s m i-is m i]. 

• Output: the borrow out s m i e B2 . 

• Side Effect: &[so • • ■ s m z_ 1 ] =>■ (m, ml). 

Note: BnnSubtract g KerN; the output s m i is 0 iff N + br < M; it is possible to 
call BnnSubtract with m = n; nl can be equal to zero, in which case the operation 

BnnSubtract is equivalent to BnnSubtractBorrow (m, ml, br). 

3.4 Multiplication 

Procedure8 Multiplication by a digit BnnMultiplyDigit: 

• C header: 

BigNumCarry BnnMultiplyDigit (p, pi, m, ml, d) 
BigNum p, m; 
unsigned pi, ml; 
BigNumDigit d; 

• Inputs: 

1. j = (p,pl) = b\po ■ ■ ■ Ppi-i], the sum; 

2. M = (m, ml) = • • -mmi-i], the multiplier, shorter than the sum: 
pi > ml. 

3. D = the multiplicand digit d. 

• Invariant: j + M x D - R = b [r 0 ■ ■ ■ V-i r P il 

• Output: the carry out r p i e B2 . 

• Side Effect: b [r 0 ■ ■ ■ V-i] (p, pi ) • 
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Note: BnnMultiplyDigit e KerN; ml can be equal to zero, in which case the carry 
out is zero and no side effect is performed; it is possible to call BnnMultiplyDigit with 
p = m; the digit d can be any digit of jor M. 

Procedure 9 Long Multiplication BnnMultiply: 

• C header: 

BigNumCarry BnnMultiply (p, pi, m, ml, n, nl) 
BigNum p, m, n; 
unsigned pi, ml, nl; 

• Inputs: 

1. j = (p,pl) = b \p 0 ■ ■ ■ p p i-i], the sum; 

2. M = (m,ml) = (,[rao •• -m m /_i], the multiplier; 

3. N = (n,nl) = &[rao •• -n^-i], the multiplicand. 

The length of operands must be such that pi > nl + ml and ml > nl; this last 
condition is imposed by speed requirements. 

• Invariant: j' + MxN = R = j,[r 0 • • -r p i-ir p i]. 

• Output: the carry out r p i e B2 . 

• Side Effect: b [r 0 ■ ■ ■ r pJ _i] ^> (p,pl). 

Note: In some implementations BnnMultiply £ KerN; it is possible to call 
BnnMultiply with n = m if in addition nl = ml special squaring code is used that is 
considerably faster than normal multiplication; when nl = 0 there is no side effect and the 
carry out is 0. 

Procedure 10 Multiply by a power of 2 BnnShif tLef t: 

• C header: 

BigNumDigit BnnShif tLef t (m, ml, nbits) 
BigNum m; 

unsigned ml, nbits; 

• Inputs: 

1. M = (m, ml ) = (,[rao • • • m m /_i], the integer to be shifted left. 

2. nbits g N, the shift amount, 0 <nbits< log 2 (b). 



Research Report No. 2 



May 1989 



10 



Bernard Serpette, Jean Vuillemin, and Jean-Claude Herve 



• Invariant: M x 2 nblts = S = b [s 0 ■ ■ -s m ;_is m ;]. 

• Output: the digit s m i shifted out. 

• Side Effects: b[so ■ ■ ■ s mi-i] => (m, ml). 

Note: BnnShif tLef t g KerN; if ml = 0 then s m i = 0. 
3.5 Division 

Procedure 1 1 Division by a digit BnnDivideDigit: 

• C header: 

BigNumDigit BnnDivideDigit (q, n, nl, d) 
BigNum q, n; 
unsigned nl; 
BigNumDigit d; 

• Inputs: 

1. J = (q, nl-1) = b[qo • • • Qnl-l],- 

2. N = (n,nl) = b[no •• -Knl-i], the dividend. 

3. D = the divisor digit d, whose value must be greater than that of the most 
significant digit oj "N: d > n n ;-i- 

• Invariant: N = DxJ + R, 0<R<D, with J = b [q 0 ■ ■ ■ q n i-i\ R = b^ol- 

• Output: the remaining digit R. 

• Side Effect: b [q 0 ■ ■ ■ q n i-i\ => (q, nl-1 ) . 

Note: BnnDivideDigit G KerN stores the nl-1 digits of the quotient in J and returns 
the remainder. 

Procedure 12 Long Division BnnDivide: 

• C header: 

void BnnDivide (n, nl, d, dl) 
BigNum n, d; 
unsigned nl, dl; 

• Inputs: 
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1. N = (n,nl) = },[no ■■■ n n ;_i], the dividend. 

2. D = (d, dl) , the divisor, shorter than the dividend: dl < nl. 

The most significant digit of the divisor must be greater than that of the dividend: 

ddl-i > n n i-i. 

Without this condition, we could not guarantee that both quotient and remainder will 
exactly fit in the storage allocated to N. 

• Invariant: N = DxJ + R, 0 < R < D, with J = b [q 0 ■ ■ ■ q n i-di-\], R = biro • • -rdi-i]- 

• Output: none 

. Side Effect: r => (n,dl); 

blqo ■ ■ -qnl-dl-U => (n+dl, nl-dl) . 

Note: BnnDivide e KerN, replaces the nl — dl most significant digits of N by the 
quotient, and the dl least significant digits by the remainder. 

Procedure 13 Divide by a power of 2 BnnShif tRight: 

• C header: 

BigNumDigit BnnShif tRight (m, ml, nbits) 
BigNum m; 

unsigned ml, nbits; 

• Inputs: 

1. M = (m, ml ) = (,[rao • • • m m /_i], the integer to be shifted right. 

2. nbits g N, the shift amount, 0 <nbits< log 2 (b). 

• Invariant: M = 2 nbits xS + Rx 2 nhits - BN - DIGIT - SIZE = 2 nbits x (S + 
R x b -1 ) with S = b[so ■ ■ ■ s m i-i], 0 < R < b. 

• Output: the shifted out digit R. 

• Side Effect: b[so • • • Smi-i] =>■ (m, ml) . 

Note: BnnShif tRight G KerN; if ml = 0 then R = 0. 

The next two procedures are used in the normalization step of long division. 

Procedure 14 BnnNumLeadingZeroBitsInDigit: 
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• C header: 

unsigned BnnNumLeadingZeroBitsInDigit (d) 
BigNumDigit d; 

• Input: digit d. 

• Invariant: \ < 2 k x (d + 1) < b. 

• Output: k. 

• Side Effect: none 

Note: BnnNumLeadingZeroBitsInDigit e KerN. The output is the number of 
most significant bits equal to zero in d. 

Procedure 15 BnnlsDigitNormalized : 

• C header: 

Boolean BnnlsDigitNormalized (d) 
BigNumDigit d; 

• Input: digit d. 

• Output: the predicate " < d < b. 

• Side Effect: none. 

Note: BnnlsDigitNormalized e KerN. 
3.6 Comparisons 

Procedure 16 Test for zero digit BnnlsDigitZero: 

• C header: 

Boolean BnnlsDigitZero (d) 
BigNumDigit d; 

• Input: digit d. 

• Output: the predicate (d = 0). 

• Side Effect: none 
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Note: BnnlsDigitZero e KerN. 

Procedure 17 Test for zero number BnnlsZero: 

• C header: 

Boolean BnnlsZero (n, nl) 
BigNum n; 
unsigned nl; 

• Input: N = (n,nl) = b [n 0 ■ ■ • n„j_i]. 

• Output: the predicate (N = 0). 

• Side Effect: none 

Note: BnnlsZero £ KerN. 

Procedure 18 Digit comparison BnnCompareDigits: 

• C header: 

BigNumCmp BnnCompareDigits ( c, d) 
BigNumDigit c, d; 

• Inputs: digits c and d. 

• Output: sgn(c - d) = {- 1, 0, 1}. 

• Side Effect: none 

Note: BnnCompareDigits e KerN. 
Procedure 19 Number comparison BnnCompare: 

• C header: 

BigNumCmp BnnCompare (m, ml, n, nl) 
BigNum m, n; 
unsigned ml, nl; 

• Inputs: 

1. M = (m,ml) = b[m 0 ■ ■ ■ m m i_i]. 

2. N = (n,nl) = b [n 0 ■ ■ -n n ;-i]- 



Research Report No. 2 



May 1989 



14 



Bernard Serpette, Jean Vuillemin, and Jean-Claude Herve 



• Output: sgn(M — N) = { — 1, 0, 1}. 

• Side Effect: none 

Note: BnnCompare £ KerN. 
Procedure 20 BnnlsDigitOdd : 

• C header: 

Boolean BnnlsDigitOdd (d) 
BigNumDigit d; 

• Input: digit d. 

• Output: the predicate (d mod 2=1). 

• Side Effect: none. 

Note: BnnlsDigitOdd <£ KerN. 
Procedure 21 BnnNumDigits : 

• C header: 

unsigned BnnNumDigits (n, nl) 
BigNum n; 
unsigned nl; 

• Input: N = (n, nl) . 

• Invariant: In = [log^(N + 1)] , if N ^ 0 and 1 otherwise. 

• Output: In. 

• Side Effect: none. 

Note: BnnNumDigits e KerN; In is the number of significant digits of N. 

3.7 Logical operations 
Procedure 22 BnnAndDigits : 

• C header: 
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void BnnAndDigits (n, d) 
BigNum n; 
BigNumDigit d; 

• Inputs 

1. N = (n, 1). 

2. D = digit d. 

• Invariant: let n&d be the bitwise logical AND o/N and D. 

• Output: none 

• Side Effect: n&d => (n,l). 

Note: BnnAndDigits e KerN. 
Procedure 23 BnnOrDigits : 

• C header: 

void BnnOrDigits (n, d) 
BigNum n; 
BigNumDigit d; 

• Inputs 

1. N = (n, 1) . 

2. D = digit d. 

• Invariant: let n v d be the bitwise logical OR o/N and D. 

• Output: none 

• Side Effect: nvd (n, 1 ) . 

Note: BnnOrDigits e KerN. 
Procedure 24 BnnXorDigits : 

• C header: 

void BnnXorDigits (n, d) 
BigNum n; 
BigNumDigit d; 
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• Inputs 

1. N = (n, 1) . 

2. D = digit d. 

• Invariant: letn@d be the bitwise EXCLUSIVE-OR o/N and D. 

• Output: none 

• Side Effect: n@d =>- (n,l). 
Note: BnnXorDigits e KerN. 

3.8 Assignments 

The following functions permit direct manipulation of the representation. 

Procedure 25 BnnSetToZero : 

• C header: 

void BnnSetToZero (n, nl) 
BigNum n; 
unsigned nl; 

• Input: N = (n,nl) = b [n 0 ■ ■ ■ n n ;-i]- 

• Output: none 

• Side Effect: 0 => (n, nl). 

Note: BnnSetToZero e KerN; if nl = 0 then no side effect is performed. 

Procedure 26 BnnSetDigit : 

• C header: 

void BnnSetDigit (n, d) 
BigNum n; 
BigNumDigit d; 

• Inputs 

1. N = (n, 1) . 

2. d is an integer 0 < d < b. 
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• Output: none 

• Side Effect: d =>- (n, 1). 

Note: BnnSetDigit e KerN. 
Procedure 27 BnnAssign : 

• C header: 

void BnnAssign (m, n, nl) 
BigNum m, n; 
unsigned nl; 

• Inputs 

1. M = (m, nl) = 6 [m 0 - • -m nJ _i]. 

2. N = (n,nl) = b [n 0 ■ • -n n ;_i]. 

• Output: 7io«e 

• Side Effect: N =>■ (m, nl). 

Note: BnnAssign e KerN; all kinds of overlapping are possible; no side effect when 
nl = 0. 

3.9 Conversion to a small integer 

In most languages, it is not possible to represent, as the value of an ordinary integer, a 
full size (e.g., 32 bit) digit. The following predicate specifies which digits can be directly 
represented by an integer in the target language. The binary length of such numbers is less than 
the package constant: BN_WORD_SI ZE. (In LeLisp , BN_WORD_SIZE=15, for example). 

Procedure 28 BnnDoesDigitFitlnWord : 

• C header: 

Boolean BnnDoesDigitFitlnWord (d) 
BigNumDigit d; 

• Input: D = digit d. 

• Output: the predicate log 2 (D) < BN_WORD_SIZE. 

• Side Effect: none. 
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Note: BnnDoesDigitFitlnWord e KerN. 
Procedure 29 BnnGetDigit : 

• C header: 

BigNumDigit BnnGetDigit (n) 
BigNum n; 

• Input N = (n,l) = n 0 , such that log 2 (n 0 ) < BN_WORD_SIZE. 

• Output: the digit uq as a regular C unsigned integer. 

• Side Effect: none 

Note: BnnGetDigit e KerN; this function does not test whether no actually fits in a 
word. 
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4 Storage allocating operations: Bz 

The layer Bz is conceptually simpler than Bn. A number z e Z is represented by a pointer 
to an array containing the sign and the digits of the base b representation of z. Procedures in 
Bz allocate storage for their results. 

4.1 Initialization Operations 
Procedure 30 Initialization Bzlnit: 

• C header: 

void Bzlnit ( ) 

• Inputs: none 

• Output: none 

• Side Effect: initializes Bz and Bn. 
Procedure 31 Closing BzClose: 

• C header: 

void BzClose ( ) 

• Inputs: none 

• Output: none 

• Side Effect: closes Bz and Bn. 

4.2 Storage operations 
Procedure 32 Allocate BzCreate: 

• C header: 

BigZ BzCreate (size) 
unsigned size; 

• Output: a number having size digits. 
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Procedure 33 Dispose BzFree: 

• C header: 

void BzFree (z) 
BigZ z; 

• Output: none 

• Side Effect: Frees the storage occupied by z. 
Procedure 34 Dispose BzFreeString: 

• C header: 

void BzFreeString (s) 
char *s; 

• Output: none 

• Side Effect: Frees the storage occupied by s (previously allocated by BzToStringj. 
Procedure 35 Physical copy Bz Copy: 

• C header: 

BigZ BzCopy (z) 
BigZ z; 

• Output: BzCopy (z) - z. 
Procedure 36 Size BzNumDigits: 

• C header: 

unsigned BzNumDigits (z) 
BigZ z; 

• Output: the number of significant digits of z. 
Procedure 37 Size BzGetSize: 

• C header: 

unsigned BzGetSize (z) 
BigZ z; 

• Output: the number of allocated digits of z. 
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4.3 Arithmetic Operations 
Procedure 38 Absolute value BzAbs 

• C header: 

BigZ BzAbs (z) 
BigZ z; 

• Output: BzAbs (z) = \z\ = sgn(z) X z. 

Procedure 39 Sign BzGetSign: 

• C header: 

BigNumCmp BzGetSign (z) 
BigZ z; 

• Output: BzGetSign (z ) = sgn(z) = {-1, 0, 1}. 

Procedure 40 Arithmetic opposite BzNegate: 

• C header: 

BigZ BzNegate (z) 
BigZ z; 

• Output: BzNegate (z) = —z. 

Procedure 41 Comparison BzCompare: 

• C header: 

BigNumCmp BzCompare (y, z) 
BigZ y, z; 

• Output: BzCompare (y, z ) = sgn(y - z) = {- 1, 0, 1}. 

Procedure 42 Addition Bz Add: 

• C header: 

BigZ BzAdd (y, z) 
BigZ y, z; 
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• Output: BzAdd(y,z) = y + z. 

Procedure 43 Subtraction Bt. Subtract: 

• C header: 

BigZ BzSubtract (y, z) 
B i g Z y , z ; 

• Output: BzSubtract (y, z) = y - z. 

Procedure 44 Multiplication BzMultiply: 

• C header: 

BigZ BzMultiply (y, z) 
BigZ y , z ; 

• Output: BzMultiply (y, z) = y X z. 



Procedure 45 Quotient BzDiv: 

• C header: 

BigZ BzDiv (y, z) 
BigZ y , z ; 

• Output: BzDiv (y,z) = y z. 
Returns NULL ifz-0. 
Returns floor(y/z) if z > 0 
otherwise returns ceil(y/z) 

where / is the real numbers division. 

Procedure 46 Modulo BzMod: 

• C header: 

BigZ BzMod (y, z) 
BigZ y , z ; 

• Output: BzMod (y, z ) = y mod z. 



Procedure 47 Division BzDivide : 
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• C header: 

BigZ BzDivide (y, z, r) 
BigZ y, z, * r ; 

• Output: the quotient y z. 
Returns NULL ifz-0. 
Returns floor(y/z) if z > 0 
otherwise returns ceil(y/z) 

where / is the real numbers division. 

• Side Effect: assigns the modulo to r such that 0 < r < abs(z) 

4.4 Read and Print 

Procedure 48 Write in base b BzToString: 

• C header: 

char* BzToString (z, b) 
BigZ z; 
unsigned b; 

• Output: BzToString(z,b) is the string representing z in base b, with 2 < b < 16. 

Procedure 49 Read in base b BzFromString: 

• C header: 

BigZ BzFromString (s, b) 
char *s; 
unsigned b; 

• Output: BzFromString ( s , b ) is the number represented by the string s, in base b 
with! < b < 16, . 

4.5 Conversions 
Procedure 50 BzFromlnteger: 

• C header: 

BigZ BzFromlnteger (i) 
int i; 
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• Output: a number equal to i. 
Procedure 51 BzToInteger: 

• C header: 

int BzToInteger (z) 
BigZ z; 

• Output: an integer equal to z iff -MAXINT < z < MAX I NT, otherwise returns 
-MAX I NT. 

Procedure 52 BzFromBigNum: 

• C header: 

BigZ BzFromBigNum (n, nl) 
BigNum n; 
unsigned nl; 

• Inputs: N = (n,nl) = b [n 0 ■ ■ ■ n n ;-i]- 

• Output: a number equal to N. 

Procedure 53 BzToBigNum: 

• C header: 

BigNum BzToBigNum (z, nl) 
BigZ z; 

unsigned * nl; 

• Output: a number N equal to z iffz > 0, otherwise returns NULL. 

• Side Effect: assigns the length of 'N to nl. 
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A What is in the package? 



Documentation Files: 
doc/bn.tex 
doc/bnf.tex 



This document in LaTeX format 

Document BigNum in French and LaTeX format 



C Include Files: 
h/BigZ .h 
h/BigNum. h 

C Source Code: 
c/bz . c 
c/bn . c 
c/KerN . c 
c/bztest . c 
c/testKerN . c 



Types and structures for clients of BigZ 
Types and structures for clients of BigNum 



BigZ implementation 

BigNum implementation ("non-kernel" routines) 
BigNum implementation ("kernel" routines) 
Test program for verifying BigZ implementation 
Test program for verifying KerN implementation 



Assembly-Language Source Code: 



s/vaxKerN . s 
s/68KerN. s 
s/ 68KerN . mot . s 
s/nsKerN . s 

Other Files: 
Makefile 



- VAX implementation of KerN 

- 68020 implementation of KerN (MIT syntax) 

- 68020 implementation of KerN (Motorola syntax) 

- NS implementation of KerN 



- Compiles source code, creates test programs 



In order to build or modify the current version of the package, 
the following commands are provided: 



make vax 
make 68K 
make ns 
make CI 6 
make C32 
make 



to use vax assembly code 

to use 68020 assembly code 

to use NS assembly code 

to use C code with 16 bit digits 

to use C code with 32 bit digits 

to use the default version (C32) 



One of these commands products the following files: 
BigNum. a - BigNum library 

bztest - Test program executable for BigZ 

testKerN - Test program executable for KerN 

If you have the tools LaTeX, makeindex and aptex, type: 

make doc - to build the Postscript files of the documents 
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B How to obtain the package? 

This document and the source code of the BigNum package bear the marking "Copyright 
Digital Equipment Corporation & INRIA 1989" This documentation and the source code of 
the BigNum package may be ordered either by postal or electronic mail from: 

Librarian 
Digital PRL 

85, Avenue Victor Hugo 

92563 Rueil Malmaison Cedex France 

(doc-server@prl.dec.com) 

(or decprl::doc-server) 

or INRIA 
Bernard Serpette 
Domaine de Voluceau 
78150 Rocquencourt France 
(serpette@inria.inria.fr) 

The source code will be sent through electronic mail. 

This documentation, and the source code of the BigNum package may be reproduced 
and distributed freely to non commercial usage provided that the following conditions are 
respected: 

• Digital PRL or INRIA should be notified of the copy. 

• The original Copyright notice should not be removed from the documentation or from 
the source code under any circumstances. 

• Any work using the BigNum package should state explicitly the use of such package, 
and its origin by including the following sentence: This work uses the BigNum package 
developed jointly by INRIA and Digital PRL. 

• If any modification is applied to the BigNum package, explicit statements should identify 
the fact that such modifications have been made, by whom, and where. These statements 
should not be removed in any further distribution. 

• Any work using extensively the BigNum package should be freely distributed under 
conditions similar to the distribution of the BigNum package. 

INRIA and Digital Equipment Corporation make no representations, express or implicit, with 
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respect to this documentation or the software it describes, including without limitations, any 
implied warranties of merchandability or fitness for a particular purpose, all of which are 
expressly disclaimed. INRIA and Digital Equipment Corporation or subsequent distributors 
shall in no event be liable for any indirect, incidental or consequential damages. 



Research Report No. 2 



May 1989 



28 



Bernard Serpette, Jean Vuillemin, and Jean-Claude Herve 



Index 
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Assign(m,n,nl), 17 

Close(), 5 

Compare(m,ml,n,nl), 13 

CompareDigits(c,d), 13 

Complement(n,nl), 7 

Divide(n,nl,d,dl), 10 

DivideDigit(q,n,nl,d), 10 

DoesDigitFitlnWord(d), 17 

GetDigit(n), 18 

Init(), 5 

IsDigitNormalized(d), 12 

IsDigitOdd(d), 14 

IsDigitZero(d), 12 

IsZero(n,nl), 13 

Multiply(p,pl,m,ml,n,nl), 9 

MultiplyDigit(p,pl,m,ml,d), 8 

NumDigits(n,nl), 14 

NumLeadingZeroBitsInDigit(d), . 11 

OrDigits(n,d), 15 

SetDigit(n,d), 16 

SetToZero(n,nl), 16 

ShiftLeft(m,ml,nbits), 9 

ShiftRight(m,ml,nbits), 11 

Subtract(m,ml,n,nl,br), 7 

SubtractBorrow(n,nl,br), 7 

XorDigits(n,d), 15 



Bz 

Abs(z), 21 

Add(y,z), 21 

Close(), 19 

Compare(y,z), 21 

Copy(z), 20 

Create(size), 19 

Div(y,z), 22 

Divide(y,z,r), 22 

Free(z), 20 

FreeString(s), 20 

FromBigNum(n,nl), 24 

Fromlnteger(i), 23 

FromString(s,b), 23 

GetSign(z), 21 

GetSize(z), 20 

Init(), 19 

Mod(y,z), 22 

Multiply(y,z), 22 

Negate(z), 21 

NumDigits(z), 20 

Subtract(y,z), 22 

ToBigNum(z,nl), 24 

Tolnteger(z), 24 

ToString(z,b), 23 
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